namespace lucere.index.read
{
    /// <summary>
    /// The TermVectorMapper can be used to map Term Vectors into your own
    /// structure instead of the parallel array structure used by
    /// IIndexReader.GetTermFreqVector(int,String).
    /// It is up to the implementation to make sure it is thread-safe.
    /// </summary>
    public interface ITermVectorMapper
    {
        /// <summary>
        /// Tell the mapper what to expect in regards to field, number of terms, offset 
        /// and position storage. This method will be called once before retrieving the 
        /// vector for a field. This method will be called before Map(string,int,ITermVectorOffsetInfo[],int[]).
        /// </summary>
        /// <param name="field">The field the vector is for</param>
        /// <param name="numTerms">The number of terms that need to be mapped</param>
        /// <param name="storeOffsets">if the mapper should expect offset information</param>
        /// <param name="storePositions">if the mapper should expect positions info</param>
        void SetExpectations(string field, int numTerms, bool storeOffsets, bool storePositions);

        /// <summary>
        /// Map the Term Vector information into your own structure
        /// </summary>
        /// <param name="term">The term to add to the vector</param>
        /// <param name="frequency">The frequency of the term in the document</param>
        /// <param name="offsets">null if the offset is not specified, otherwise the offset into the field of the term</param>
        /// <param name="positions">null if the position is not specified, otherwise the position in the field of the term</param>
        void Map(string term, int frequency, ITermVectorOffsetInfo[] offsets, int[] positions);

        /// <summary>
        /// Indicate to Lucene that even if there are positions stored, 
        /// this mapper is not interested in them and they can be skipped over.  
        /// Derived classes should set this to true if they want to ignore 
        /// positions.  The default is false, meaning positions will be 
        /// loaded if they are stored.
        /// </summary>
        bool IsIgnoringPositions { get; } 

        /// <summary>
        /// See IsIgnoringPositions. Same principal as IsIgnoringPositions, but applied to offsets.  false by default.
        /// </summary>
        bool IsIgnoringOffsets { get; }

        /// <summary>
        /// Passes down the index of the document whose term vector is currently being mapped,
        /// once for each top level call to a term vector reader. Default implementation IGNORES 
        /// the document number.  Override if your implementation needs the document number.
        /// <para>
        /// NOTE: Document numbers are internal to Lucene and subject to change depending 
        /// on indexing operations.
        /// </para>
        /// </summary>
        /// <param name="documentNumber">index of document currently being mapped</param>
        void SetDocumentNumber(int documentNumber);
    }
}